Polling confirmations (under Experimental spi) #1115

younata · 2025-05-15T06:19:55Z

This implements polling confirmations, as described in ST-NNNN.

Motivation:

Being able to monitor changes in the background is something of immense value. Swift Testing already provides an API for this in the confirmation api. However, I've found the confirmation to be hard to work with at times - it requires you to set up a callback for when something changes, which is not always possible or even the right thing to do. Polling provides a very general approach to monitoring all kinds of changes.

Modifications:

This adds a new set of macros for handling polling. A new public enum for the 2 separate polling behaviors, and new types to actually implement polling. All under the experimental spi.

Checklist:

Code and documentation should follow the style of the Style Guide.
If public symbols are renamed or modified, DocC references should be updated.

Sources/Testing/Polling/Polling.swift

Tests/TestingTests/PollingTests.swift

Additionally, make PollingBehavior an implementation detail of polling, instead of exposed publicly Removes any timeouts involved for polling, as they become increasingly unreliable as the system runs more and more tests

…figuration trait Stop unnecessarily waiting after the last polling attempt has finished. Allow for subsequent polling configuration traits which specified nil for a value to fall back to earlier polling configuration traits before falling back to the default.

These two mirror their confirm counterparts, only throwing an error (instead of recording an issue) when they fail.

…the PollingRecorder actor. Now, this uses a separate method for evaluating polling to remove that actor.

Removed the duplicate poll method, and made evaluate-returning-bool into a wrapper for evaluate-returning-optional

This is less direct, but much more intuitive for test authors. Also add exit tests confirming that these values are non-negative

Follow more english-sentence-like guidance for function naming Simplify the polling confirmation API down to just 2 public functions, 1 enum, and 1 error type. Always throw an error when polling fails, get rid of the separate issue recording.

Instead of mulitple traits per stop condition, just have a single trait per stop condition.

Preliminary implementation of polling expectations

1d9ea96

younata requested review from stmontgomery, grynspan, briancroom and suzannaratcliff as code owners May 15, 2025 06:19

grynspan assigned younata May 18, 2025

grynspan added enhancement New feature or request public-api Affects public API api-proposal API proposal PRs (documentation only) issue-handling Related to Issue handling within the testing library macros 🔭 Related to Swift macros such as @Test or #expect labels May 18, 2025